Add scout-issue skill: find and rank GitHub issues to contribute to 🤖🤖🤖 by shauryagangrade · Pull Request #6243 · github/awesome-copilot

shauryagangrade · 2026-11-04T05:16:27Z

What this adds

Adds skills/scout-issue/, a skill that helps a developer find the best GitHub issues to contribute to in a repository. Triggered by /scout, it:

Interviews the user about experience level, languages/frameworks, available time, contribution type, difficulty, and constraints
Inspects the repo and pulls candidate issues with the GitHub CLI (with graceful fallbacks when gh is missing, unauthenticated, or rate-limited)
Scores each candidate on eight weighted dimensions (user fit, technical fit, scope, difficulty, issue quality, activity, feasibility, evidence quality)
Presents a ranked shortlist with explicit evidence, concerns, and confidence

It also supports investigation mode ("Investigate #123") and implementation planning ("Plan this issue"). The skill is read-only by default, separates evidence from inference, and never ranks by title match alone or trusts good first issue labels without checking the issue and surrounding code.

What's bundled

SKILL.md — the concise four-phase pipeline, eligibility gates, and rules
references/ — interview guide, scoring rubric, workflow walkthrough, GitHub CLI/git patterns, investigation and planning templates, recovery fallbacks, and a quick reference
examples/ — worked scenarios: first contribution, weekend project, deep investigation, portfolio contribution, no good matches, and a real cli/cli run
scripts/validate-skill.sh — consistency check (structure, headings, command paths and flags, reference sync, per-fixture negative checks, and a nonzero sync-failure regression)

Every bundled asset is referenced from SKILL.md.

Real-issue run

examples/copilot-run.md captures a concise run against cli/cli on 2026-11-06. It shows the issue-only candidate pool, the eligibility screen, why #14647 was excluded because open PR #14689 already competed for it, and how the final ranking was re-checked against assignments, linked PRs, code locations, and activity.

Validation

npm run skill:validate — passes (all skills valid)
npm run build — regenerated docs/README.skills.md
bash eng/fix-line-endings.sh — run
bash skills/scout-issue/scripts/validate-skill.sh — passes from the skill folder

Notes

The skill name is scout-issue (matching the folder and source project); the trigger command remains /scout.
The main SKILL.md was shortened from 559 to 271 lines by moving interview, investigation/planning templates, and recovery guidance into referenced material.
Source project: https://github.com/shauryagangrade/scout-issue (Apache-2.0; the bundled LICENSE is preserved). Submitted by the original author.

Adds the scout-issue skill (/scout), which interviews a developer about experience level, skills, available time, and contribution type, then searches a repository's GitHub issues, scores candidates against a weighted rubric, and presents a ranked, evidence-backed shortlist. Bundles the reference docs (scoring rubric, workflow, CLI patterns, quick reference), worked examples, a consistency-check script, and a small launcher that prints SKILL.md.

github-actions · 2026-11-04T05:16:55Z

🚦 Submission status: 🛠️ Requires submitter fixes

Risk tier: merge-risk:high — Privileged execution, automation, or review-policy change
Required to merge: passing submission-gate checks plus 1 approval from reviewers with write access, including a maintainer with admin or maintain permission.

Why this tier

skills/scout-issue/scripts/validate-skill.sh is a high-risk path (automation, scripts, MCP config, hooks, or review policy)
Label needs-review:HIGH flags a high contributor-risk signal

Automated checks

Check	Status	Details
Line endings	✅ Passed	Passed · logs
Spelling	✅ Passed	Passed · logs
Generated README consistency	✅ Passed	Passed · logs
Skill validation	✅ Passed	Passed · logs
Skill lint (vally)	✅ Passed	Passed · logs
Risk scan	✅ Passed	Passed · logs
Contributor reputation	✅ Passed	Passed · logs
Duplicate resource scan	✅ Passed	Passed · logs
PR quality signal	⏭️ Skipped	Skipped by its workflow · logs

Action needed

Address the changes requested by aaronpowell, then push an update.

Review

Approvals: 0/1
Assigned reviewer: aaronpowell
Review target date: not set
Still needed: 1 more approval(s); an approval from a maintainer with admin or maintain permission; resolution of changes requested by aaronpowell
The core-maintainers pool is not staffed yet; an approver with admin or maintain permission is required instead.

Commands

Command	Who	What it does
`/rerun-checks`	PR author, maintainers	Re-runs failed or incomplete checks and re-evaluates this gate
`/request-review`	PR author, maintainers	Asks the review rotation to assign a reviewer (adds `needs-reviewer`)

_{Updated for 0f178d6 · gate run · This comment is maintained automatically — see submission gate docs.}

github-actions · 2026-11-04T05:16:59Z

🔒 PR Risk Scan Results

Scanned 17 changed file(s).

Severity	Count
🔴 High	0
🟠 Medium	0
ℹ️ Info	1

Severity	Rule	File	Line	Match
ℹ️	`skill-script-touched`	`skills/scout-issue/scripts/validate-skill.sh`	1	`skills/scout-issue/scripts/validate-skill.sh`

This is an automated soft-gate report. Findings indicate review targets and do not block merge by themselves.

github-actions · 2026-11-04T05:17:03Z

🔴 Contributor Reputation Check: HIGH risk

Check	Risk
Profile	HIGH
Credential audit	NONE

Maintainers: please review this contributor before merging.
See the workflow run for full details.
Automated check powered by AGT.

github-actions · 2026-11-04T05:17:58Z

🔍 Vally Lint Results

✅ All checks passed

Scope	Checked
Skills	1
Agents	0
Total	1

Severity	Count
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	✅ scout-issue (2/2 checks passed)
ℹ️	✓ [spec-compliance] All 1 skill(s) are spec-compliant.
ℹ️	✓ spec-compliance: All spec checks passed.
ℹ️	✓ [valid-refs] All file references across 1 skill(s) are valid.
ℹ️	✓ valid-refs: All file references resolve to existing files within the skill directory.
ℹ️	1 skill(s) linted, 1 passed

Full linter output

### Linting skills/scout-issue
✅ scout-issue (2/2 checks passed)
    ✓ [spec-compliance] All 1 skill(s) are spec-compliant.
        ✓ spec-compliance: All spec checks passed.
    ✓ [valid-refs] All file references across 1 skill(s) are valid.
        ✓ valid-refs: All file references resolve to existing files within the skill directory.

1 skill(s) linted, 1 passed

Copilot

🟡 Changes recommended

Unsupported GitHub CLI flags, unreliable candidate filtering, and shortcuts that bypass required checks can cause discovery failures and unsuitable recommendations, while the validator fails to catch invalid commands.

9 open issues

What changed in this PR

Adds scout-issue to the repository’s skill collection to help developers discover, evaluate, and rank GitHub issues suited to their experience and available time.

Changes:

Defines issue discovery, weighted ranking, investigation, and implementation-planning workflows.
Bundles scoring guidance, command references, worked examples, and a consistency-check script.
Registers the skill in the generated catalog and preserves its Apache-2.0 license.

File	Description
`skills/scout-issue/SKILL.md`	Defines the workflow, output formats, and fallback behavior.
`skills/scout-issue/scripts/validate-skill.sh`	Checks structure, headings, commands, and reference consistency.
`skills/scout-issue/references/workflow.md`	Details discovery, filtering, investigation, and ranking.
`skills/scout-issue/references/tool-patterns.md`	Supplies GitHub CLI and Git command examples.
`skills/scout-issue/references/scoring-rubric.md`	Defines scoring dimensions and adapted weights.
`skills/scout-issue/references/quick-reference.md`	Summarizes commands, checks, and output conventions.
`skills/scout-issue/LICENSE`	Preserves the source project’s Apache-2.0 license.
`skills/scout-issue/examples/weekend-project.md`	Demonstrates time-constrained recommendations.
`skills/scout-issue/examples/skill-matching.md`	Demonstrates matching issues to technical skills.
`skills/scout-issue/examples/portfolio-contribution.md`	Illustrates portfolio-focused recommendations.
`skills/scout-issue/examples/no-good-matches.md`	Demonstrates rejection reasons and alternatives.
`skills/scout-issue/examples/first-contribution.md`	Illustrates recommendations for new contributors.
`skills/scout-issue/examples/deep-investigation.md`	Demonstrates a detailed contribution brief.
`docs/README.skills.md`	Adds the skill’s catalog entry and asset list.

_{Review effort: Balanced (auto)}

…--files -> gh pr diff, open-PR filter, stale removed, compact Phase 4, validate flags+subcommands

Copilot

🟡 Changes recommended

Incorrect search scoping, eligibility filters, and pagination can produce unsuitable issue recommendations, while validator gaps allow documented errors to pass undetected.

9 open issues

1 previously missed issue

In code that hasn't changed since last review

Use an issue-only count for the search population

skills/scout-issue/SKILL.md:164

GitHub's repository open_issues_count includes open pull requests as well as issues. Using it as the “from M open issues” figure overstates the search population; for example, a repository with one issue and many PRs will report all of them as issues. Query an issue-only count instead.

8 resolved since last review

_{Review effort: Balanced (auto)}

…eline source.issue.state, validator flags+search

Copilot

🟡 Changes recommended

The validator can report success despite reference-sync failures and silently accepted negative fixtures, leaving substantive validation gaps unresolved.

7 open issues

1 previously missed issue

In code that hasn't changed since last review

Snapshot fixture error count before sync checks

skills/scout-issue/scripts/validate-skill.sh:188

Reference-sync failures are counted as expected negative-fixture failures because fixture_errors is calculated after the sync loop. With otherwise valid docs, a sync failure therefore prints an error but still exits zero and reports success. Snapshot the fixture count immediately after checking the negative fixtures, before the guard and sync checks.

3 resolved since last review

_{Review effort: Balanced (auto)}

aaronpowell

Thanks for adding a focused contribution-discovery workflow. A few concrete fixes are needed:

In SKILL.md:184, gh search issues does not support --page. Please use working REST pagination, filter out pull requests, and correct the claimed open-issue total at lines 162–164: open_issues_count includes PRs.
In scripts/validate-skill.sh:187–188, reference-sync failures are included in fixture_errors and subtracted from the real error count. Capture expected fixture failures before the sync checks, assert each negative fixture independently, and add a regression case proving a sync failure exits nonzero.
SKILL.md:18 references bin/scout.js, but that file is absent. Remove the reference or include the intended asset.
Please shorten the 559-line main skill, retaining the specific scoring/eligibility logic while consolidating the generic interview, evidence rules and investigation/implementation templates into referenced material.

Please also include a concise GitHub Copilot run against real issues showing the candidate pool, why a competing-PR issue was excluded, and how the final ranking was checked. The current validation establishes formatting and internal consistency, not the discovery workflow's behavior.

…skill - Use an issue-only search count and REST pagination that filters pull requests - Scope search commands to the repository and make assignment/stale filters conditional - Assert each negative fixture independently, snapshot fixture errors before sync checks, and add a nonzero sync regression - Remove the missing bin/scout.js reference - Move interview, investigation/planning templates, and recovery guidance into references; cut SKILL.md from 559 to 271 lines - Add examples/copilot-run.md with a real cli/cli run, including a competing-PR exclusion

Describe the label/text searches that expanded the candidate pool and state that code paths were verified through the repository contents API rather than a local checkout.

Copilot

🟡 Changes recommended

The pagination rule can skip valid candidates, portfolio weights contradict the documented formula, and the misplaced Git limit can return a file’s entire history.

5 open issues

Paginate before filtering pull requests · New
Align portfolio weights with the documented formula · New
Place the history limit before the path separator · New
Remove unrequested filters from the example · New
Replace duplicated checklists with scout-specific guidance · New

7 resolved since last review

_{Review effort: Balanced (auto)}

Copilot

🔵 Needs a closer look

Unresolved scoring inconsistencies, unsupported eligibility filters, and pagination and Git command errors can change rankings, exclude eligible candidates, and collect incomplete or excessive history.

5 open issues

_{Review effort: Balanced (auto)}

Copilot

🟡 Changes recommended

The scanner lets invalid flags on backslash-continuation lines pass validation, and the shortlist output omits promised per-issue confidence and verification gaps.

2 open issues

5 resolved since last review

_{Review effort: Balanced (auto)}

Copilot

🔵 Needs a closer look

Human assessment is needed because incomplete linked-PR checks and permissive recovery behavior may allow claimed or unverified work into the ranked recommendations.

No open issues 🎉

2 resolved since last review

_{Review effort: Balanced (auto)}

shauryagangrade · 2026-11-07T11:08:46Z

@aaronpowell could you take another look at this PR when you have a moment? Happy to adjust anything that still needs work.

aaronpowell

Thanks for addressing the earlier workflow issues and adding the real cli/cli run. One invocation detail remains: the skill frontmatter and SKILL.md advertise /scout, but this PR adds only a skill named scout-issue and no prompts/scout.prompt.md or other /scout alias. Please either add a Copilot prompt alias for /scout, or update the trigger and examples to use the supported activation method for this skill so users can reliably start the workflow.

The skill name is the slash command, so /scout was never a valid invocation. Document /scout-issue and the natural-language triggers that activate the skill automatically.

shauryagangrade · 2026-11-09T08:22:26Z

Thanks @aaronpowell — good catch. A skill's name is the slash command, so /scout was never a valid invocation for this skill. This repo also has no prompts/ category, so I went with the supported activation method instead of adding a prompt alias.

Updated in 0f178d6:

Frontmatter now says Invoke with /scout-issue or ask to find good first issues…
SKILL.md, references/quick-reference.md, and references/recovery.md use /scout-issue throughout.
Documented the natural-language triggers that activate the skill automatically (e.g. "Find a beginner-friendly Rust issue I could finish this weekend").
Regenerated docs/README.skills.md.

npm run skill:validate passes.

Copilot

🔵 Needs a closer look

Human review is needed to assess validation blind spots and conflicting eligibility and confidence guidance that could undermine the skill’s reliability.

No open issues 🎉

_{Review effort: Balanced (auto)}

shauryagangrade requested review from a team as code owners November 4, 2026 05:16

Copilot AI auto review requested due to automatic review settings November 4, 2026 05:16

github-actions Bot added new-submission PR adds at least one new contribution skills PR touches skills awaiting-automation merge-risk:high labels Nov 4, 2026

github-actions Bot added the needs-review:HIGH Contributor reputation check flagged HIGH risk label Nov 4, 2026

Copilot started reviewing on behalf of shauryagangrade November 4, 2026 05:17

View session

github-actions Bot added the skill-check-error Skill validator reported errors label Nov 4, 2026

github-actions Bot added ready-for-review Submission passed intake validation and is ready for maintainer review and removed awaiting-automation labels Nov 4, 2026

Copilot AI reviewed Nov 4, 2026

View reviewed changes

Fix scout-issue review feedback (PR github#6243): --sort via search, …

f52fb57

…--files -> gh pr diff, open-PR filter, stale removed, compact Phase 4, validate flags+subcommands

Copilot AI auto review requested due to automatic review settings November 4, 2026 06:14

github-actions Bot added awaiting-automation and removed ready-for-review Submission passed intake validation and is ready for maintainer review labels Nov 4, 2026

Copilot started reviewing on behalf of shauryagangrade November 4, 2026 06:15

View session

github-actions Bot added ready-for-review Submission passed intake validation and is ready for maintainer review and removed awaiting-automation labels Nov 4, 2026

Copilot AI reviewed Nov 4, 2026

View reviewed changes

Address new scout-issue review: unless filter, REST PR-inclusion, tim…

2c8467a

…eline source.issue.state, validator flags+search

Copilot AI auto review requested due to automatic review settings November 4, 2026 08:09

github-actions Bot added awaiting-automation and removed ready-for-review Submission passed intake validation and is ready for maintainer review labels Nov 4, 2026

Copilot AI reviewed Nov 4, 2026

View reviewed changes

Comment thread skills/scout-issue/references/workflow.md Resolved

aaronpowell requested changes Nov 6, 2026

View reviewed changes

github-actions Bot added requires-submitter-fixes Submission has quality-gate findings that submitter must fix before maintainer review and removed ready-for-review Submission passed intake validation and is ready for maintainer review labels Nov 6, 2026

Copilot AI auto review requested due to automatic review settings November 6, 2026 06:57

Copilot started reviewing on behalf of shauryagangrade November 6, 2026 06:58

View session

github-actions Bot removed the skill-check-error Skill validator reported errors label Nov 6, 2026

Clarify real-issue run evidence

6f877d3

Describe the label/text searches that expanded the candidate pool and state that code paths were verified through the repository contents API rather than a local checkout.

Copilot AI reviewed Nov 6, 2026

View reviewed changes

Copilot AI auto review requested due to automatic review settings November 6, 2026 07:04

Copilot started reviewing on behalf of shauryagangrade November 6, 2026 07:05

View session

Copilot AI reviewed Nov 6, 2026

View reviewed changes

Address scout-issue review: pagination, weights, and example constraints

c6122d8

Copilot AI auto review requested due to automatic review settings November 6, 2026 07:22

Copilot started reviewing on behalf of shauryagangrade November 6, 2026 07:23

View session

Copilot AI reviewed Nov 6, 2026

View reviewed changes

Comment thread skills/scout-issue/scripts/validate-skill.sh Resolved

Comment thread skills/scout-issue/references/quick-reference.md Resolved

Validate continued commands and report shortlist confidence

905bbee

Copilot AI auto review requested due to automatic review settings November 6, 2026 08:08

Copilot started reviewing on behalf of shauryagangrade November 6, 2026 08:09

View session

Copilot AI reviewed Nov 6, 2026

View reviewed changes

shauryagangrade requested a review from aaronpowell November 9, 2026 03:06

aaronpowell requested changes Nov 9, 2026

View reviewed changes

Use the supported /scout-issue invocation

0f178d6

The skill name is the slash command, so /scout was never a valid invocation. Document /scout-issue and the natural-language triggers that activate the skill automatically.

Copilot AI auto review requested due to automatic review settings November 9, 2026 08:22

Copilot started reviewing on behalf of shauryagangrade November 9, 2026 08:22

View session

Copilot AI reviewed Nov 9, 2026

View reviewed changes

shauryagangrade requested a review from aaronpowell November 9, 2026 08:28

Conversation

shauryagangrade commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this adds

What's bundled

Real-issue run

Validation

Notes

Uh oh!

github-actions Bot commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚦 Submission status: 🛠️ Requires submitter fixes

Automated checks

Action needed

Review

Commands

Uh oh!

github-actions Bot commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔒 PR Risk Scan Results

Uh oh!

github-actions Bot commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Vally Lint Results

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

aaronpowell left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

shauryagangrade commented Nov 4, 2026 •

edited

Loading

github-actions Bot commented Nov 4, 2026 •

edited

Loading

github-actions Bot commented Nov 4, 2026 •

edited

Loading

github-actions Bot commented Nov 4, 2026 •

edited

Loading

github-actions Bot commented Nov 4, 2026 •

edited

Loading